home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / utils / xad / developer / include / autodocs / xadsub.doc < prev   
Text File  |  1999-01-01  |  9KB  |  225 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadForeman/--Overview--
  4. xadClient/--Overview--
  5. xadClient/xcFree
  6. xadClient/xcGetInfo
  7. xadClient/xcRecogData
  8. xadClient/xcUnArchive
  9.  
  10. VERSION
  11.     $VER: xadsub.doc 1.3 (14.03.1999) by SDI
  12.  
  13. xadForeman/--Overview--                               xadForeman/--Overview--
  14.  
  15. The xadForeman structure is just some kind of header for external clients.
  16. It protects the clients from being executed accidentally by having a small
  17. piece of code (MOVEQ #-1,d0 : RTS) in the first 4 bytes.
  18. The master can identify a valid bunch of external clients by checking the
  19. first hunk of a file for the foreman identification.
  20. Finally, a foreman holds the pointer to a linked list of clients and thus
  21. enables the master to work with these clients.
  22.  
  23. xadClient/--Overview--                                 xadClient/--Overview--
  24.  
  25. The xadClient structure is the heart of the whole library system. Each
  26. client enables the master to recognize and unarchive files.
  27.  
  28. Therefore each client contains 4 routines that are called from the master.
  29. Pointers to these are stored in xc_RecogData, xc_GetInfo, xc_UnArchive and
  30. xc_Free.
  31.  
  32. All routines have one thing in common: the CPU registers D0/D1/A0/A1 are
  33. so-called scratch registers, they may change during execution, all other
  34. registers must remain unchanged. CPU register A6 holds a pointer to the
  35. xadMasterBase structure. See chapters below for a description of the client
  36. routines.
  37.  
  38. ALL CLIENT ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC
  39. MEMORY AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT
  40. THE ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME! DO
  41. NOT EXCEED STACK USAGE (1KB SHOULD BE THE MAXIMUM), AS PROGRAMS NORMALLY
  42. HAVE ONLY 4KB STACK.
  43.  
  44. The name of the archiver that is supported by the client and the flags that
  45. describe the packer are stored in xc_ArchiverName and xc_Flags. Internal
  46. clients all have an unique ID value stored in xc_Identifier. If you have
  47. written a client that should replace an internal one, because it is faster
  48. or otherwise enhanced, simply put the ID of the client to be replaced in
  49. xc_Identifier. The old client will then be taken out of the list of used
  50. clients. Normally this ID should be zero. There is one problem with this:
  51. When the user deactivates external clients the xadmaster system is missing
  52. this type completely as internal client is not activated in this case.
  53.  
  54. xcRecogData() usually only requires a quite small part of a file to
  55. recognize it properly. To avoid reading the whole file for recognition
  56. purposes, you need to set xc_RecogSize to the minimum amount of bytes
  57. that is required to recognize the crunched file correctly.
  58. Note that xadmaster uses this value internally to decide whether a file
  59. might be archived with a archiver or not, so you don't have to do an extra
  60. size comparison in your xc_RecogData function any more.
  61. For archiver headers with non-constant sizes, simply set xc_RecogSize
  62. to a value that will ensure correct recognition of all possible files.
  63.  
  64. Whenever you intend to use features of the xadmaster.library in your
  65. clients that are marked (V2) or higher, make sure to set xc_MasterVersion
  66. to the desired version number, otherwise an old library version might
  67. crash while using the new client.
  68.  
  69. Whenever a client calls a xadmaster function and gets a return code, the
  70. client needs to return this code! So whenever an error code is produced
  71. somewhere, it must reach the calling program. This is most important
  72. for progress report (automatically called by xadHookAccess), as the
  73. XADERR_SKIP can be checked by calling program.
  74.  
  75. ANY needed structure must be allocated with xadAllocObject! None of the
  76. XAD structures can be allocated any other way!
  77.  
  78. xadClient/xcFree                                             xadClient/xcFree
  79.  
  80.    NAME
  81.     xcFree -- Free all resources allocated by xcGetInfo
  82.  
  83.    SYNOPSIS
  84.     xcFree(ai, xadMasterBase)
  85.            A0       A6
  86.  
  87.     void xcFree(struct xadArchiveInfo *, struct xadMasterBase *)
  88.  
  89.    FUNCTION
  90.     This function frees all the stuff allocated by xcGetInfo. It is
  91.     called after unsuccessful xcGetInfo as well, so you need not to
  92.     call any freeing functions there. But be prepared for that case.
  93.     You must check all entries, as xcGetInfo may fail in the first
  94.     allocation stages (f.e. allocation of xadDiskInfo or xadFileInfo
  95.     structures).
  96.     Clear all entries you have freed! There should not be any pointers
  97.     left in xadArchiveInfo structure which do not point to valid
  98.     memory.
  99.  
  100.    INPUTS
  101.     ai    the master communication structure
  102.  
  103.    SEE ALSO
  104.     Example sourcecodes, xadmaster.library/xadFreeInfo()
  105.  
  106. xadClient/xcGetInfo                                       xadClient/xcGetInfo
  107.  
  108.    NAME
  109.     xcGetInfo -- create all information about an archive file
  110.  
  111.    SYNOPSIS
  112.     result = xcGetInfo(ai, xadMasterBase)
  113.       D0               A0        A6
  114.  
  115.     LONG xcGetInfo(struct xadArchiveInfo *, struct xadMasterBase *)
  116.  
  117.    FUNCTION
  118.     This function is the most important one. It creates a structure
  119.     list containing all necessary information. File archivers create
  120.     a linked list of xadFileInfo structures for every file/link/
  121.     directory which is stored in the archive. xadAllocObject helps
  122.     to store that information by providing 3 tags for getting special
  123.     memory. XAD_OBJNAMESIZE can be used to allocate a buffer for
  124.     storing (also multiple) names. The buffer is byte aligned. Do not
  125.     forget to count the 0-byte for every string you want to store there.
  126.     The buffer pointer is stored in xfi_FileName.
  127.     XAD_OBJCOMMENTSIZE is equal to this, but stored in xfi_Comment.
  128.     For file and disk archives there is the flag XAD_OBJPRIVINFOSIZE,
  129.     which returns a longword aligned buffer in xfi_PrivateInfo or
  130.     xdi_PrivateInfo.
  131.     Disk archivers create a linked list of xadDiskInfo structures.
  132.     Normal disk archivers do not allow to store more than one archive,
  133.     so linking is most time not necessary, but it is supported.
  134.     When storing information texts, they must be finished with a zero
  135.     byte, which is not counted in size field!
  136.     Every file or disk entry gets an entrynumber, which increases from
  137.     first to last entry. For mixed archivers this means that a
  138.     "file, disk, disk, file, file, disk" archive gets file entry
  139.     numbers 1,4,5 and disk entry numbers 2,3,6.
  140.     Archivers may store XADAIF_FILECORRUPT flag in xai_Flags, when 
  141.     archive is corrupt, but some entries are still usable. Unusable
  142.     entries must not appear in entry list.
  143.     Most disk archivers are based on cylinder structure. These should
  144.     fill the xadDiskInfo fields correctly. If archivers are not based
  145.     on it (e.g. only sector based) they need to set XADDIF_NOCYLINDER
  146.     flag!
  147.     If the archiver format does not support file dates, set the
  148.     current date (XAD_DATECURRENTIME tag) and XADFIF_NODATE flag.
  149.     Protection bits default to zero (equals "rwed").
  150.  
  151.    INPUTS
  152.     ai    master communication structure
  153.  
  154.    RESULT
  155.         result    - any of the XADERR codes or zero when all is ok.
  156.  
  157.    SEE ALSO
  158.     Example sourcecodes, xadmaster.library/xadGetInfo()
  159.  
  160. xadClient/xcRecogData                                   xadClient/xcRecogData
  161.  
  162.    NAME
  163.     xcRecogData -- Scan input buffer for known archiver type
  164.  
  165.    SYNOPSIS
  166.     result = xcRecogData(size, buffer, xadMasterBase)
  167.       D0                  D0     A1         A6
  168.  
  169.     BOOL xcRecogData(ULONG, STRPTR, struct xadMasterBase *)
  170.  
  171.    FUNCTION
  172.     Returns non zero when this buffer is part of a archive file
  173.     supported by this client. The recognition should be very stable.
  174.     It should be tested with lots of files. One wrong recognition
  175.     for 100000 files is acceptable.
  176.  
  177.    INPUTS
  178.     size    size of passed buffer
  179.     buffer    buffer containing start of file to scan
  180.  
  181.    RESULT
  182.     result - TRUE if archiver is recogniced, FALSE if not
  183.  
  184.    SEE ALSO
  185.     Example sourcecodes, xadmaster.library/xadRecogFile(),
  186.     xadmaster.library/xadGetInfo()
  187.  
  188. xadClient/xcUnArchive                                   xadClient/xcUnArchive
  189.  
  190.    NAME
  191.     xcUnArchive -- write the required entry to destination
  192.  
  193.    SYNOPSIS
  194.     result = xcUnArchive(ai, xadMasterBase)
  195.       D0                 A0        A6
  196.  
  197.     LONG xcUnArchive(struct xadArchiveInfo *, struct xadMasterBase *)
  198.  
  199.    FUNCTION
  200.     This function dearchives one entry. The required entry is passed
  201.     in xai_CurFile or xai_CurDisk. A normal client will support only
  202.     one of the two possibilities, but clients using file and/or disk
  203.     archives are allowed as well. When writing disk data, the client
  204.     should write data in blocks with size of multiple sectorsize.
  205.     Although it should work, it is not recommended to write blocks
  206.     unequal to this.
  207.     Nearly all information you may need is stored in xadArchiveInfo
  208.     structure.
  209.     You may expect the entries to be unarchived in same order as they
  210.     are numbered, but it is not necessary!
  211.     Disk archivers may expect to be called again to dearchive an
  212.     entry, even if there is only one! So restore the file position
  213.     you need to unarchive.
  214.  
  215.    INPUTS
  216.     ai    master communication structure
  217.  
  218.    RESULT
  219.         result    - any of the XADERR codes or zero when all is ok.
  220.  
  221.    SEE ALSO
  222.     Example sourcecodes, xadmaster.library/xadDiskunArc(),
  223.     xadmaster.library/xadFileUnArc()
  224.  
  225.